3D Graphics Programming with QuickDraw 3D 1.5.4

Analyzing the Object Hierarchy

QuickDraw 3D provides routines to help you analyze its object hierarchy.

An example of using object hierarchy analysis functions is given in Listing 4 . This example recursively prints all the subclasses for a particular class to stdout , assuming that an ANSI C support library is available. If you wanted to print out the entire class hierarchy for QuickDraw 3D, you could use this routine in the way shown at the end of the example.

Listing 4 Example of hierarchy analysis



 
void PrintClassAndRecurse(

    TQ3ObjectType   objectClassType, 

    int             depth)

{

    TQ3SubClassData             subClassData;

    TQ3ObjectClassNameString    objectClassString;

    unsigned long               index;



 
    depth++;

    if (objectClassType != kQ3ObjectTypeInvalid) {



 
        Q3ObjectHierarchy_GetStringFromType(objectClassType, 

            objectClassString);



 
        for (index = 0; index < depth; index++) {

            printf(" ");

        }



 
        printf("%s\n", objectClassString);



 
        Q3ObjectHierarchy_GetSubClassData(objectClassType, &subClassData);



 
        for (index = 0; index < subClassData.numClasses; index++) {

            /* recurse on each subclass type */

            PrintClassAndRecurse(subClassData.classTypes[index], depth);

        }



 
        Q3ObjectHierarchy_EmptySubClassData(&subClassData);

    }

    depth--;

}



 
/*

*   The class "Object" is in fact a virtual base class -- it is not

*   possible to instantiate this class. At the root of the hierarchy

*   are four classes: View, Pick, Element, and Shared. So we can go from

*   each of these classes, instead of going from "Object".

*/



 
    printf("Root Object (virtual metaclass)\n");

    PrintClassAndRecurse(kQ3ObjectTypeView, 0);

    PrintClassAndRecurse(kQ3ObjectTypeElement, 0);

    PrintClassAndRecurse(kQ3ObjectTypePick, 0);

    PrintClassAndRecurse(kQ3ObjectTypeShared, 0);

Q3ObjectHierarchy_GetTypeFromString

You can use the Q3ObjectHierarchy_GetTypeFromString function to obtain the class type for a given class name.



 
typedef char    TQ3ObjectClassNameString[kQ3StringMaximumLength];

kQ3StringMaximumLength = 1024



 
TQ3Status Q3ObjectHierarchy_GetTypeFromString(

                     TQ3ObjectClassNameString    objectClassString,

                     TQ3ObjectType               *objectClassType);

objectClassString: A class name as a C string.
objectClassType: On return, the class type.

DESCRIPTION

The Q3ObjectHierarchy_GetTypeFromString function returns, in the objectClassType parameter, the class type associated with the name in the objectClassString parameter. If objectClassString is invalid, the routine will return kQ3Failure .

Q3ObjectHierarchy_GetStringFromType

You can use the Q3ObjectHierarchy_GetStringFromType function to obtain the class name for a given class type.



 
TQ3Status Q3ObjectHierarchy_GetStringFromType(

                     TQ3ObjectType               objectClassType,

                     TQ3ObjectClassNameString    objectClassString);

objectClassType: A class type.
objectClassString: On return, a class name as a C string.

DESCRIPTION

The Q3ObjectHierarchy_GetStringFromType function returns, in the objectClassString parameter, the class name associated with the type in the objectClassType parameter. If objectClassType is invalid, the routine will return kQ3Failure .

Q3ObjectHierarchy_IsTypeRegistered

You can use the Q3ObjectHierarchy_IsTypeRegistered function to determine if a class type is registered.



 
TQ3Boolean Q3ObjectHierarchy_IsTypeRegistered(

                     TQ3ObjectType    objectClassType);

objectClassType: A class type.

DESCRIPTION

The Q3ObjectHierarchy_IsTypeRegistered function returns TRUE if the class type specified by objectClassType is registered and FALSE otherwise.

Q3ObjectHierarchy_IsNameRegistered

You can use the Q3ObjectHierarchy_IsNameRegistered function to determine if a class name is registered.



 
TQ3Boolean Q3ObjectHierarchy_IsNameRegistered(

                     const char    *objectClassName);

objectClassName: A class name as a C string.

DESCRIPTION

The Q3ObjectHierarchy_IsNameRegistered function returns TRUE if the class name specified by objectClassName is registered and FALSE otherwise.

Q3ObjectHierarchy_GetSubClassData

You can use the Q3ObjectHierarchy_GetSubClassData function to obtain the number and class types of all the subclasses immediately below a class in the QuickDraw 3D class hierarchy.



 
typedef struct TQ3SubClassData {

    unsigned long    numClasses;    /* the # of subclass types found */

    TQ3ObjectType    *classTypes;   /* an array of class types */

} TQ3SubClassData;



 
TQ3Status Q3ObjectHierarchy_GetSubClassData(

                     TQ3ObjectType      objectClassType,

                     TQ3SubClassData    *subClassData);

objectClassType: An object class type.
subClassData: Pointer to a TQ3SubClassData struct containing the number and class types of the subclasses below objectClassType.

DESCRIPTION

The Q3ObjectHierarchy_GetSubClassData function returns, in the subClassData parameter, the number and class types of all the subclasses immediately below the class designated by objectClassType.

This call must be followed by a call to Q3ObjectHierarchy_EmptySubClassData to avoid memory leaks.

Q3ObjectHierarchy_EmptySubClassData

You must use the Q3ObjectHierarchy_EmptySubClassData function to free memory allocated by Q3ObjectHierarchy_GetSubClassData.



 
TQ3Status Q3ObjectHierarchy_EmptySubClassData(

                     TQ3SubClassData    *subClassData);

subClassData: Pointer to a TQ3SubClassData struct.

DESCRIPTION

The Q3ObjectHierarchy_EmptySubClassData function frees memory allocated for subClassData by a previous call to Q3ObjectHierarchy_GetSubClassData.